package flexserverlib.services;

import javax.mail.Message;

/**
 * @author Andrew Powell - Universal Mind - andrew.powell@universalmind.com
 */
public interface IPOP3Service {
    /**
     * Connect to the pop3 server.
     *
     * @throws Exception If an error occurs.
     */
    void connect() throws Exception;

    /**
     * Disconnect from the pop3 server.
     *
     * @throws Exception If an error occurs.
     */
    void disconnect() throws Exception;

    /**
     * Returns the number of messages in the users inbox.
     *
     * @return int The number of messages in the users inbox.
     * @throws Exception If an error occurs.
     */
    int getMessageCount() throws Exception;

    /**
     * Returns the number of unread messages in the users folder.
     *
     * @return int The number of unread messages in the users folder.
     * @throws Exception If an error occurs.
     */
    int getUnreadMessageCount() throws Exception;

    /**
     * Returns the number of new messages in the users folder.
     *
     * @return int The number of new messages in the users folder.
     * @throws Exception If an error occurs.
     */
    int getNewMessageCount() throws Exception;

    /**
     * Get the Message object corresponding to the given message number.
     *
     * @param msgnum The index/message number of the message to get.
     * @return Message The message at the specified index.
     * @throws Exception If an error occurs.
     */
    Message getMessage(int msgnum) throws Exception;

    /**
     * Get all Message objects from this Folder.
     *
     * @return Message[] The array of messages.
     * @throws Exception If an error occurs.
     */
    Message[] getMessages() throws Exception;

    /**
     * Get the Message objects for message numbers specified in the array.
     *
     * @param msgnums An integer array containing the index/message
     *                number of the messages to get.
     * @return Message[] The array of messages.
     * @throws Exception If an error occurs.
     */
    Message[] getMessages(int[] msgnums) throws Exception;

    /**
     * Get the Message objects for message numbers ranging from start through
     * end, both start and end index inclusive.
     *
     * @param start The index/message number to start getting messages at.
     * @param end   The index/message number to stop getting messages at.
     * @return Message[] The array of messages.
     * @throws Exception If an error occurs.
     */
    Message[] getMessages(int start, int end) throws Exception;
}
